Tool Results

BindAI tools use ToolResult as their execution result type. ToolResult records:

whether execution succeeded
the value produced by the tool
an error message when execution failed

It provides a small, consistent result contract that can be used by tools, workflows, and the Studio runtime.

ToolResult

The V1 ToolResult is a dataclass that extends BindAI’s ExecutionResult:

from bindai_tool import ToolResult

Its fields are:

ToolResult(
    success: bool,
    value: Any = None,
    error: str | None = None,
)

The fields are:

Field	Description
`success`	Whether tool execution succeeded
`value`	The value produced by the tool
`error`	Error information when execution fails

ToolResult uses slots=True. The important distinction is:

successful execution is represented by success=True
the successful result is stored in value
failed execution is represented by success=False
failure information is stored in error

Creating Successful Results

ToolResult provides the ok() class method for creating a successful result:

from bindai_tool import ToolResult

result = ToolResult.ok(20)

This produces:

ToolResult(
    success=True,
    value=20,
    error=None,
)

A successful result can also contain no value:

result = ToolResult.ok()

which represents:

ToolResult(
    success=True,
    value=None,
    error=None,
)

None in value does not by itself indicate failure. Always use result.success to determine whether execution succeeded.

Creating Failed Results

ToolResult also provides the failed() class method:

from bindai_tool import ToolResult

result = ToolResult.failed(
    "Unable to retrieve the requested data."
)

The result is:

ToolResult(
    success=False,
    value=None,
    error="Unable to retrieve the requested data.",
)

The failed() method accepts the failure message as a string. For example:

try:
    ...
except Exception as exc:
    result = ToolResult.failed(str(exc))

This keeps the failure representation consistent with the rest of the tool runtime.

Tool Implementations

The Tool base class defines the execution contract for class-based tools. A Tool implementation provides:

name
description
definition
execute(context)

The execute() method returns a ToolResult:

from bindai_tool import Tool, ToolResult

class ExampleTool(Tool):

    @property
    def name(self) -> str:
        return "example"

    @property
    def description(self) -> str:
        return "Example BindAI tool."

    @property
    def definition(self):
        ...

    def execute(self, context) -> ToolResult:
        return ToolResult.ok("done")

A successful execution therefore returns:

ToolResult.ok("done")

A failed execution can return:

ToolResult.failed("The operation could not be completed.")

Checking Success

Applications can inspect the success field:

result = some_tool_result

if result.success:
    print(result.value)
else:
    print(result.error)

This is the standard pattern for handling a ToolResult. For example:

if result.success:
    value = result.value
else:
    error = result.error

Do not determine success solely by checking whether value is None. A successful tool can legitimately return:

ToolResult.ok(None)

Accessing the Returned Value

A successful tool value is available through value:

result = ToolResult.ok(49)

print(result.value)

Output:

The field used by ToolResult for the tool’s successful value is:

result.value

This is the field to use when handling a ToolResult directly. Because ToolResult also extends ExecutionResult, BindAI’s broader execution-result interface can expose additional execution information where appropriate. The tool-specific successful value remains result.value.

Returning Different Python Values

Tools can produce normal Python values.

Strings

ToolResult.ok("Pong")

The value is:

result.value

and contains:

Pong

Numbers

ToolResult.ok(25)

The value is:

Lists

ToolResult.ok(
    ["red", "green", "blue"]
)

The value is the list:

result.value

Dictionaries

ToolResult.ok(
    {
        "name": "Alice",
        "age": 28,
    }
)

The dictionary is available through:

result.value

ToolResult.value accepts arbitrary Python values. The value should nevertheless be chosen with its downstream consumer in mind, particularly when the result will be passed into another workflow node or exposed through the Studio API.

`None` as a Successful Value

A tool can successfully complete without producing a meaningful value. For example:

ToolResult.ok()

represents:

ToolResult(
    success=True,
    value=None,
    error=None,
)

This is different from:

ToolResult(
    success=False,
    value=None,
    error="Operation failed.",
)

The correct way to distinguish the two is:

if result.success:
    # Successful execution
    ...
else:
    # Failed execution
    ...

Handling Tool Failures

A tool failure can be represented explicitly:

return ToolResult.failed(
    "Customer could not be found."
)

The caller can then inspect:

if not result.success:
    print(result.error)

This produces a consistent failure representation without requiring callers to know how the underlying tool implemented the operation.

Exceptions and Tool Results

A Tool implementation controls the ToolResult returned from its execute() method. For example:

def execute(self, context) -> ToolResult:
    try:
        value = perform_operation()

        return ToolResult.ok(value)

    except Exception as exc:
        return ToolResult.failed(str(exc))

This explicitly converts the operation into the BindAI tool result contract. The error message should be useful to the caller without exposing secrets or other sensitive implementation details. For example, avoid putting credentials directly into an error message.

Tool Results in Workflows

Tools can be executed as workflow nodes. A Tool node can produce a ToolResult that becomes part of workflow execution state. Conceptually:

Workflow
   |
   v
 Tool Node
   |
   v
ToolResult
   |
   +-- success --> value available for later processing
   |
   +-- failure --> error information

BindAI’s workflow runtime preserves the ToolResult object in workflow variables. This is important because workflow execution state is richer than the JSON representation returned by the Studio API. For example, a tool result can be stored as:

ToolResult(
    success=True,
    value={
        "status": "ok",
        "count": 3,
    },
)

A subsequent workflow operation can work with that result according to the workflow’s configured mappings and execution behavior.

Tool Results and Parameter Mapping

When a Tool node is used in a workflow, its inputs can be mapped from workflow variables. For example:

type: tool
tool: echo
output_variable: tool_output
parameter_mapping:
  text: input

The Tool node receives the mapped value and executes the registered tool. The tool’s execution result is then associated with the configured output variable. This allows a workflow to connect tool execution to later nodes:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
Condition / Agent / Tool / End

The important distinction is that parameter mapping controls the inputs to the tool, while ToolResult represents the result of the tool execution.

Agent and Tool Results

Tool results and agent results serve different purposes. A tool execution uses:

ToolResult

while an agent execution uses the agent execution result defined by the BindAI agent runtime. When working directly with a ToolResult, use:

result.success
result.value
result.error

Do not assume that an agent result and a tool result have identical fields or behavior.

Tool Results and Connection-backed Tools

BindAI V1 also uses ToolResult for connection-backed tools. For example, the V1 Webhook connection is exposed to workflows as a connection-backed tool. Its tool implementation returns a ToolResult:

return ToolResult(
    success=True,
    output=result,
    value=result,
)

If the connection operation fails, it returns a failed result:

return ToolResult(
    success=False,
    output=None,
    value=None,
    error=str(exc),
)

This means the workflow does not need a separate result type for a normal project tool and a connection-backed tool. Both use the same tool result contract.

Studio API Representation

The workflow runtime can contain rich Python objects such as ToolResult. The Studio HTTP API converts these runtime values into JSON-safe data before returning them to an API client. For a successful ToolResult, the Studio API exposes the underlying successful value. For example, a runtime result such as:

ToolResult(
    success=True,
    value={
        "status": 200,
    },
)

can be represented through the Studio API as:

{
  "status": 200
}

A failed ToolResult is represented with failure information. For example:

ToolResult(
    success=False,
    error="Webhook request failed",
)

can be exposed as:

{
  "success": false,
  "error": "Webhook request failed"
}

This conversion happens at the API boundary. It does not change the workflow runtime’s internal ToolResult contract.

ToolResult and ExecutionResult

ToolResult extends BindAI’s ExecutionResult:

class ToolResult(ExecutionResult):
    ...

This allows tool results to participate in BindAI’s broader execution-result model while still providing tool-specific fields:

result.success
result.value
result.error

The inheritance relationship is useful when tool execution is part of a larger runtime operation, such as workflow execution. It does not mean that all execution-result types have exactly the same application-level fields or semantics.

Current API

The verified V1 ToolResult API is:

from bindai_tool import ToolResult

Constructor:

ToolResult(
    success: bool,
    value: Any = None,
    error: str | None = None,
)

Class methods:

ToolResult.ok(value=None)

and:

ToolResult.failed(message)

The primary attributes are:

result.success
result.value
result.error

Example:

success = ToolResult.ok(42)

failure = ToolResult.failed(
    "Something went wrong."
)

Then:

success.success
# True

success.value
# 42

failure.success
# False

failure.error
# "Something went wrong."

What Is Not Part of the V1 ToolResult API

The V1 API does not require a separate ToolExecutor abstraction. There is no verified V1 executor.py implementation in bindai-tool. Therefore, application code should not depend on an API such as:

ToolExecutor(...)

or:

executor.execute(...)

unless such an abstraction is introduced by a later BindAI version. Likewise, do not assume additional result helper methods that are not part of the verified API. The verified convenience methods are:

ToolResult.ok(...)
ToolResult.failed(...)

Predictable Tool Values

Tool outputs should be designed with their downstream consumers in mind. For structured operations, predictable dictionaries can be useful:

return ToolResult.ok(
    {
        "id": 42,
        "name": "Alice",
        "active": True,
    }
)

The successful value can then be accessed through:

result.value

and, when appropriate:

result.value["name"]

Keep output structures stable when other tools or workflow nodes depend on them.

Error Messages

Tool errors can flow into workflows, applications, or API responses. Avoid exposing sensitive information such as:

API keys
access tokens
passwords
connection credentials
private connection strings
sensitive personal information

For example, prefer:

return ToolResult.failed(
    "Unable to retrieve the customer."
)

over exposing an underlying credential or authentication header. Error messages should provide enough information to understand the failure while remaining safe for the layer that will consume the result.

Testing Tool Results

Tools should be tested for both successful and failed execution. A successful result:

result = ToolResult.ok(20)

assert result.success is True
assert result.value == 20
assert result.error is None

A failed result:

result = ToolResult.failed(
    "Invalid input."
)

assert result.success is False
assert result.value is None
assert result.error == "Invalid input."

It is also useful to test successful execution with a None value:

result = ToolResult.ok()

assert result.success is True
assert result.value is None

This verifies that callers do not incorrectly interpret None as failure.

Best Practices

Use ToolResult.ok(...) for successful class-based tool execution.
Use ToolResult.failed(...) for explicit tool failures.
Check result.success before consuming the result.
Read successful values from result.value.
Read failure information from result.error.
Do not use value is None as the success test.
Keep tool output structures predictable.
Keep error messages useful but safe.
Do not expose credentials or sensitive data through errors.
Test both successful and failed execution.
Remember that ToolResult extends ExecutionResult.
Treat workflow ToolResult values as runtime objects rather than assuming they are already JSON.
Let the Studio API perform the JSON conversion at the HTTP boundary.

Complete Example

A class-based tool can return ToolResult directly:

from bindai_tool import Tool, ToolResult


class MultiplyTool(Tool):

    @property
    def name(self) -> str:
        return "multiply"

    @property
    def description(self) -> str:
        return "Multiply two integers."

    @property
    def definition(self):
        ...

    def execute(self, context) -> ToolResult:
        try:
            a = context.variables.get("a")
            b = context.variables.get("b")

            return ToolResult.ok(a * b)

        except Exception as exc:
            return ToolResult.failed(str(exc))

The successful execution produces:

ToolResult(
    success=True,
    value=42,
    error=None,
)

A failure produces:

ToolResult(
    success=False,
    value=None,
    error="...",
)

The caller can handle both cases through the same interface:

result = tool.execute(context)

if result.success:
    print(result.value)
else:
    print(result.error)

Summary

ToolResult is BindAI’s V1 result type for tool execution. Its core structure is:

ToolResult
├── success
├── value
└── error

Successful results can be created with:

ToolResult.ok(value)

Failed results can be created with:

ToolResult.failed(message)

The primary interface is:

result.success
result.value
result.error

ToolResult extends ExecutionResult, allowing tool results to participate in BindAI’s broader execution model. In workflows, the runtime can preserve the full ToolResult object, while the Studio API converts runtime values into JSON-safe responses for HTTP clients. The result contract therefore remains consistent across project tools, workflow Tool nodes, and the V1 Webhook connection-backed tool.

​Tool Results

​ToolResult

​Creating Successful Results

​Creating Failed Results

​Tool Implementations

​Checking Success

​Accessing the Returned Value

​Returning Different Python Values

​Strings

​Numbers

​Lists

​Dictionaries

​None as a Successful Value

​Handling Tool Failures

​Exceptions and Tool Results

​Tool Results in Workflows

​Tool Results and Parameter Mapping

​Agent and Tool Results

​Tool Results and Connection-backed Tools

​Studio API Representation

​ToolResult and ExecutionResult

​Current API

​What Is Not Part of the V1 ToolResult API

​Predictable Tool Values

​Error Messages

​Testing Tool Results

​Best Practices

​Complete Example

​Summary